

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>7. Examples &mdash; Python v2.7.8 documentation</title>
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2.7.8',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/sidebar.js"></script>
    <link rel="search" type="application/opensearchdescription+xml"
          title="Search within Python v2.7.8 documentation"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="Python v2.7.8 documentation" href="../index.html" />
    <link rel="up" title="Distributing Python Modules" href="index.html" />
    <link rel="next" title="8. Extending Distutils" href="extending.html" />
    <link rel="prev" title="6. The Python Package Index (PyPI)" href="packageindex.html" />
    <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
    <script type="text/javascript" src="../_static/copybutton.js"></script>
    
 
    

  </head>
  <body>  
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="extending.html" title="8. Extending Distutils"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="packageindex.html" title="6. The Python Package Index (PyPI)"
             accesskey="P">previous</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="http://www.python.org/">Python</a> &raquo;</li>
        <li>
          <a href="../index.html">Python v2.7.8 documentation</a> &raquo;
        </li>

          <li><a href="index.html" accesskey="U">Distributing Python Modules</a> &raquo;</li> 
      </ul>
    </div>    

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="examples">
<span id="id1"></span><h1>7. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h1>
<p>This chapter provides a number of basic examples to help get started with
distutils.  Additional information about using distutils can be found in the
Distutils Cookbook.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="http://wiki.python.org/moin/Distutils/Cookbook">Distutils Cookbook</a></dt>
<dd>Collection of recipes showing how to achieve more control over distutils.</dd>
</dl>
</div>
<div class="section" id="pure-python-distribution-by-module">
<span id="pure-mod"></span><h2>7.1. Pure Python distribution (by module)<a class="headerlink" href="#pure-python-distribution-by-module" title="Permalink to this headline">¶</a></h2>
<p>If you&#8217;re just distributing a couple of modules, especially if they don&#8217;t live
in a particular package, you can specify them individually using the
<em class="xref std std-option">py_modules</em> option in the setup script.</p>
<p>In the simplest case, you&#8217;ll have two files to worry about: a setup script and
the single module you&#8217;re distributing, <tt class="file docutils literal"><span class="pre">foo.py</span></tt> in this example:</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        foo.py</pre>
</div>
<p>(In all diagrams in this section, <em>&lt;root&gt;</em> will refer to the distribution root
directory.)  A minimal setup script to describe this situation would be:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foo&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;foo&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>Note that the name of the distribution is specified independently with the
<em class="xref std std-option">name</em> option, and there&#8217;s no rule that says it has to be the same as
the name of the sole module in the distribution (although that&#8217;s probably a good
convention to follow).  However, the distribution name is used to generate
filenames, so you should stick to letters, digits, underscores, and hyphens.</p>
<p>Since <em class="xref std std-option">py_modules</em> is a list, you can of course specify multiple
modules, eg. if you&#8217;re distributing modules <tt class="xref py py-mod docutils literal"><span class="pre">foo</span></tt> and <tt class="xref py py-mod docutils literal"><span class="pre">bar</span></tt>, your
setup might look like this:</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        foo.py
        bar.py</pre>
</div>
<p>and the setup script might be</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="s">&#39;bar&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>You can put module source files into another directory, but if you have enough
modules to do that, it&#8217;s probably easier to specify modules by package rather
than listing them individually.</p>
</div>
<div class="section" id="pure-python-distribution-by-package">
<span id="pure-pkg"></span><h2>7.2. Pure Python distribution (by package)<a class="headerlink" href="#pure-python-distribution-by-package" title="Permalink to this headline">¶</a></h2>
<p>If you have more than a couple of modules to distribute, especially if they are
in multiple packages, it&#8217;s probably easier to specify whole packages rather than
individual modules.  This works even if your modules are not in a package; you
can just tell the Distutils to process modules from the root package, and that
works the same as any other package (except that you don&#8217;t have to have an
<tt class="file docutils literal"><span class="pre">__init__.py</span></tt> file).</p>
<p>The setup script from the last example could also be written as</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>(The empty string stands for the root package.)</p>
<p>If those two files are moved into a subdirectory, but remain in the root
package, e.g.:</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        src/      foo.py
                  bar.py</pre>
</div>
<p>then you would still specify the root package, but you have to tell the
Distutils where source files in the root package live:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;&#39;</span><span class="p">:</span> <span class="s">&#39;src&#39;</span><span class="p">},</span>
      <span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>More typically, though, you will want to distribute multiple modules in the same
package (or in sub-packages).  For example, if the <tt class="xref py py-mod docutils literal"><span class="pre">foo</span></tt>  and <tt class="xref py py-mod docutils literal"><span class="pre">bar</span></tt>
modules belong in package <tt class="xref py py-mod docutils literal"><span class="pre">foobar</span></tt>, one way to layout your source tree is</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py</pre>
</div>
<p>This is in fact the default layout expected by the Distutils, and the one that
requires the least work to describe in your setup script:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;foobar&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>If you want to put modules in directories not named for their package, then you
need to use the <em class="xref std std-option">package_dir</em> option again.  For example, if the
<tt class="file docutils literal"><span class="pre">src</span></tt> directory holds modules in the <tt class="xref py py-mod docutils literal"><span class="pre">foobar</span></tt> package:</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        src/
                 __init__.py
                 foo.py
                 bar.py</pre>
</div>
<p>an appropriate setup script would be</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;foobar&#39;</span><span class="p">:</span> <span class="s">&#39;src&#39;</span><span class="p">},</span>
      <span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;foobar&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>Or, you might put modules from your main package right in the distribution
root:</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        __init__.py
        foo.py
        bar.py</pre>
</div>
<p>in which case your setup script would be</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;foobar&#39;</span><span class="p">:</span> <span class="s">&#39;&#39;</span><span class="p">},</span>
      <span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;foobar&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>(The empty string also stands for the current directory.)</p>
<p>If you have sub-packages, they must be explicitly listed in <em class="xref std std-option">packages</em>,
but any entries in <em class="xref std std-option">package_dir</em> automatically extend to sub-packages.
(In other words, the Distutils does <em>not</em> scan your source tree, trying to
figure out which directories correspond to Python packages by looking for
<tt class="file docutils literal"><span class="pre">__init__.py</span></tt> files.)  Thus, if the default layout grows a sub-package:</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py
                 subfoo/
                           __init__.py
                           blah.py</pre>
</div>
<p>then the corresponding setup script would be</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span> <span class="s">&#39;foobar.subfoo&#39;</span><span class="p">],</span>
      <span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="single-extension-module">
<span id="single-ext"></span><h2>7.3. Single extension module<a class="headerlink" href="#single-extension-module" title="Permalink to this headline">¶</a></h2>
<p>Extension modules are specified using the <em class="xref std std-option">ext_modules</em> option.
<em class="xref std std-option">package_dir</em> has no effect on where extension source files are found;
it only affects the source for pure Python modules.  The simplest  case, a
single extension module in a single C source file, is:</p>
<div class="highlight-python"><pre>&lt;root&gt;/
        setup.py
        foo.c</pre>
</div>
<p>If the <tt class="xref py py-mod docutils literal"><span class="pre">foo</span></tt> extension belongs in the root package, the setup script for
this could be</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="kn">from</span> <span class="nn">distutils.extension</span> <span class="kn">import</span> <span class="n">Extension</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s">&#39;foo.c&#39;</span><span class="p">])],</span>
      <span class="p">)</span>
</pre></div>
</div>
<p>If the extension actually belongs in a package, say <tt class="xref py py-mod docutils literal"><span class="pre">foopkg</span></tt>, then</p>
<p>With exactly the same source tree layout, this extension can be put in the
<tt class="xref py py-mod docutils literal"><span class="pre">foopkg</span></tt> package simply by changing the name of the extension:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="kn">from</span> <span class="nn">distutils.extension</span> <span class="kn">import</span> <span class="n">Extension</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;foobar&#39;</span><span class="p">,</span>
      <span class="n">version</span><span class="o">=</span><span class="s">&#39;1.0&#39;</span><span class="p">,</span>
      <span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s">&#39;foopkg.foo&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s">&#39;foo.c&#39;</span><span class="p">])],</span>
      <span class="p">)</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">7. Examples</a><ul>
<li><a class="reference internal" href="#pure-python-distribution-by-module">7.1. Pure Python distribution (by module)</a></li>
<li><a class="reference internal" href="#pure-python-distribution-by-package">7.2. Pure Python distribution (by package)</a></li>
<li><a class="reference internal" href="#single-extension-module">7.3. Single extension module</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="packageindex.html"
                        title="previous chapter">6. The Python Package Index (PyPI)</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="extending.html"
                        title="next chapter">8. Extending Distutils</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
  <li><a href="../bugs.html">Report a Bug</a></li>
  <li><a href="../_sources/distutils/examples.txt"
         rel="nofollow">Show Source</a></li>
</ul>

<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>  
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="extending.html" title="8. Extending Distutils"
             >next</a> |</li>
        <li class="right" >
          <a href="packageindex.html" title="6. The Python Package Index (PyPI)"
             >previous</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="http://www.python.org/">Python</a> &raquo;</li>
        <li>
          <a href="../index.html">Python v2.7.8 documentation</a> &raquo;
        </li>

          <li><a href="index.html" >Distributing Python Modules</a> &raquo;</li> 
      </ul>
    </div>  
    <div class="footer">
    &copy; <a href="../copyright.html">Copyright</a> 1990-2014, Python Software Foundation.
    <br />
    The Python Software Foundation is a non-profit corporation.
    <a href="http://www.python.org/psf/donations/">Please donate.</a>
    <br />
    Last updated on Jun 29, 2014.
    <a href="../bugs.html">Found a bug</a>?
    <br />
    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
    </div>

  </body>
</html>